---
title: clsPrint
summary: API reference for clsPrint.
status: draft
owner: SAIF Documentation
last_reviewed: 2026-08-21
library: SAIF.Services.Printing
reference_type: embedded
---

# clsPrint

`clsPrint` is the xPression protocol/transport gateway for this library: it owns endpoint resolution against
the SAIF Environment API, request assembly for preview/print/distribute operations, the synchronous-versus-MSMQ-
queued dispatch decision, and the MSMQ transaction lifecycle. It is constructed either from an injected
`EnvironmentServiceBase` or, via the parameterless constructor, from the ambient `AppGlobal.EnvironmentService`.
It depends on `SAIF.Services.Imaging.Import.clsImageImport` as the imaging index payload carried on `ImportInfo`
and `CompositeRequestClass.Importinfo`, and is consumed directly by presentation/business callers such as
`LegalMaintenance/frmPrintPreview.aspx.vb` and by `ReportBase` as the underlying print/preview client for a
report's lifecycle.

## Purpose
- Resolve the xPression `documentGeneratorServiceUrl` endpoint and the `documentMSMQPath` MSMQ queue path from
  the Environment API at construction time
- Provide preview, print, and distribute operations against the xPression `clsGenerate` SOAP service
- Select between a synchronous SOAP distribute call and a transactional MSMQ-queued distribute request based on
  the `Asynchronous` flag ([BR-PRT-003](../../business-rules.md#br-prt-003-synchronous-versus-queued-distribution))
- Manage the MSMQ transaction lifecycle so multiple distribute calls can be batched into one unit of work
  ([BR-PRT-004](../../business-rules.md#br-prt-004-transactional-msmq-send))

## Context
- Namespace: `SAIF.Services.Printing`
- Assembly/package: `SAIF.Services.Printing` (embedded library, project reference)

## Public members
| Member | Signature | Purpose |
| --- | --- | --- |
| `IDMEnvs` | `Public Enum IDMEnvs {Dev, Test, QA, Prod, NonImaged}` | Declares imaging-environment tokens; not referenced by any code in this library** |
| `CompositeRequestClass` | `<Serializable()> Public Class` (nested) | MSMQ message payload aggregating package, XML, printer, plex/scale/copies, format, output profile, `clsImageImport`, email/fax/deferred info, IDM path, and paper tray; `ToString` renders a labelled multi-line diagnostic dump |
| `Application` | `Public Property As String` | xPression calling-application token sent on every service call; defaults to `"xPression Design"` |
| `Asynchronous` | `Public Property As Boolean` | Selects the MSMQ queue path instead of the direct SOAP call for `distributeDocument` ([BR-PRT-003](../../business-rules.md#br-prt-003-synchronous-versus-queued-distribution)) |
| `Copies` | `Public Property As Int16` | Print copy count sent to xPression; defaults to `1` |
| `Environment` | `Public ReadOnly Property As String` | Two-valued environment label (`"Prod"`/`"Dev"`) derived once in the constructor from `EnvironmentServiceBase.IsProduction` ([BR-PRT-002](../../business-rules.md#br-prt-002-environment-label-derivation)) |
| `Format` | `Public Property As String` | Requested output format placed on a queued distribution request; defaults to `"PDF"` |
| `ImportInfo` | `Public Property As clsImageImport` | Imaging index metadata carried with the distribution; lazily instantiated on first read |
| `OutputProfile` | `Public Property As String` | xPression output profile name; defaults to `"PDF"` |
| `Package` | `Public Property As String` | xPression package (document) name; the setter strips a trailing `.pkg` extension ([BR-PRT-001](../../business-rules.md#br-prt-001-package-name-extension-normalization)) |
| `PlexMode` | `Public Property As xpresso.PlexMode` | Simplex/duplex selection; defaults to `Simplex` |
| `Printer` | `Public Property As String` | Target printer queue name |
| `ScaleMode` | `Public Property As xpresso.ScaleMode` | Page scaling selection; defaults to `None` |
| `XML` | `Public Property As String` | xPression data XML supplied to the composition engine |
| `FaxInfo` | `Public Property As FaxInfoClass` | Fax delivery detail block; lazily instantiated on read |
| `EmailInfo` | `Public Property As EmailInfoClass` | E-mail delivery detail block; lazily instantiated on read |
| `DeferredInfo` | `Public Property As DeferredPrintInfoClass` | Deferred-print delivery detail block; lazily instantiated on read |
| `IDMPath` | `Public ReadOnly Property As String` | Imaging drop path read live from the Environment API key `idmFilePath` on each access |
| `New()` | `Public Sub New()` | Resolves the environment service from the ambient `AppGlobal.EnvironmentService` and delegates to the parameterised constructor |
| `New(envSvc)` | `Public Sub New(envSvc As EnvironmentServiceBase)` | Creates the xPression proxy, sets its `Url` from `documentGeneratorServiceUrl`, reads the MSMQ path from `documentMSMQPath`, and sets the `Environment` label |
| `previewPDF` | `Function previewPDF(inPackage As String, inXML As String) As Byte()` | Returns rendered PDF bytes from xPression `previewPDF` under the literal `"xPression Design"` application token |
| `previewDocument` | `Function previewDocument(inPackage As String, inXML As String) As Byte()` / `(inPackage As String, inXML As String, inOutputProfile As String) As Byte()` | Returns rendered document bytes for the package/XML using the current or supplied output profile; used by the print-preview screen |
| `printPDF` | `Function printPDF(inFile As Byte()) As Boolean` | Sends already-rendered bytes to xPression for physical printing with the current printer/plex/copies/scale; always returns `True` ([BR-PRT-013](../../business-rules.md#br-prt-013-print-and-distribute-report-unconditional-success)) |
| `distributeDocument` | `Function distributeDocument(inPackage As String, inXML As String) As Boolean` | Entry point for full document distribution (queue or direct); always returns `True` ([BR-PRT-013](../../business-rules.md#br-prt-013-print-and-distribute-report-unconditional-success)) |
| `StartMQTransaction` | `Public Sub StartMQTransaction()` | Begins an MSMQ transaction if one is not already open (idempotent) |
| `EndMQTransaction` | `Public Sub EndMQTransaction(inAction As Boolean)` | Commits when `True`, aborts when `False`, then disposes and clears the transaction in a `Finally` block |
| `xpublishDocument` | `Function xpublishDocument(inPackage As String, inXML As String, inDestination As String, inLabel As String) As Boolean` | Publishes the package/XML to the named xPression destination using the current application token |
| `xpreviewHTML` | `Function xpreviewHTML(inPackage As String, inXML As String, inOutputProfile As String) As String` | Returns the rendered HTML preview for a package/XML under the selected output profile |
| `xpublishAndReturnDocument` | `Function xpublishAndReturnDocument(inPackage As String, inXML As String, inDestination As String, inLabel As String) As Byte()` | Publishes the package/XML and returns the generated document bytes instead of only a success flag |
| `xdocumentsForCategory` | `Function xdocumentsForCategory(inCategory As String) As String()` | Returns the xPression document names available within the requested category |
| `xoutputProfilesForDocument` | `Function xoutputProfilesForDocument(inPackage As String) As String()` | Returns the available xPression output profiles for the specified package |
| `xcategoriesForUser` | `Function xcategoriesForUser(inUser As String) As String()` | Returns the xPression document categories visible to the supplied user name |

## Behavioral notes
- `distributeDocument` branches on `Asynchronous`: when true, it lazily creates a transactional
  `MessageQueue(m_MessagePath)`, builds a `CompositeRequestClass`, sends it with `BinaryMessageFormatter`, and
  commits (starting a transaction itself if the caller had not); a failure rolls back and re-throws
  ([BR-PRT-004](../../business-rules.md#br-prt-004-transactional-msmq-send), [BR-PRT-005](../../business-rules.md#br-prt-005-msmq-failure-rollback)). When false, it calls the xPression `distributeDocument` SOAP
  operation directly with paper tray hard-coded to `Tray2` ([BR-PRT-006](../../business-rules.md#br-prt-006-fixed-paper-tray-for-synchronous-distribution)).
- The queued `CompositeRequestClass` does not carry a paper tray value — `Tray` is left at its default, unlike
  the synchronous path's hard-coded `Tray2`.*
- Reading `ImportInfo` lazily instantiates a `clsImageImport`, but the private helper that builds the
  synchronous distribute call reads `ImportInfoString` instead, which returns `""` when no `ImportInfo` was
  explicitly set — it does not trigger the lazy instantiation.*
- `previewPDF` always passes the literal `"xPression Design"` application token rather than the configurable
  `Application` property.*

## Constraints and usage notes
- The parameterised constructor is `Public`, so the environment service can be substituted for testing; the
  parameterless constructor couples construction to the ambient static `AppGlobal.EnvironmentService`.
- Callers batching multiple asynchronous distributions should call `StartMQTransaction` before the first
  `distributeDocument` call and `EndMQTransaction` after the last, since `distributeDocument` will otherwise
  start and commit its own single-message transaction.

> **Note:** Statements marked with * were inferred from code structure, naming conventions, or
> contextual evidence where direct confirmation was not available in source artifacts. Statements
> marked with ** could not be confirmed; treat as unknown until verified.

## Sources
- SAIF.Services.Printing/clsPrint.vb